-----------------------
Important Note
-----------------------

PostgreSQL requires that all large object operations be peformed inside of a transaction. Therefore, you must start a transaction before you perform your first large object operation, like this:

db.SQLExecute "BEGIN TRANSACTION"

After you have performed your last large object operation, you should close the transaction, like this:

db.SQLExecute "END TRANSACTION"




-----------------------
Summary
-----------------------

PostgreSQLDatabase implements PostgreSQL's large objects with the following API:

PostgreSQLDatabase Methods:

CreateLargeObject() as Integer: create a large object and return its id. Legal ids are positive integers. Therefore, if CreateLargeObject returns 0 or less, then there was an error creating the large object. Use ErrorMessage to determine what the error was.

DeleteLargeObject(oid as Integer): delete the large object with id 'oid'.

OpenLargeObject(oid as Integer, readOnly as Boolean = false) as PostgreSQLLargeObject: open the large object with id 'oid'. The 'readOnly' argument is optional and defaults to false. If you pass true as the value for 'readOnly', then the large object will be opened in read-only mode. If OpenLargeObject is successful, it will return an instance of PostgreSQLLargeObject.


PostgreSQLLargeObject Methods:

Close(): close the large object.

Read(count as Integer) as String: read 'count' bytes from the large object and return them as a String.

Write(data as String): write 'data' to the large object.

Seek(offset as Integer, whence as Integer): positions the large object at 'offset' relative to the beginning, end, or current position of the large object, as determined by the value of 'whence'. Possible values for whence, and what they mean, are as follows:

0: offset is relative to the beginning of the large object
1: offset is relative to the current position of the large object
2: offset is relative to the end of the large object

So, for example, if you wanted to position a large object at its end, you could call Seek as follows:

lo.Seek(0, 2)

The following Seek positions the large object at its beginning:

lo.Seek(0, 0)

Offsets can be negative as well, For example, the following call of Seek positions the large object 10 bytes before its current position:

lo.Seek(-10, 1)


Tell() as Integer: return the current position of the large object.


PostgreSQLLargeObject Properties:

Length as Integer: a read-only property that returns the length of the large object.

Position as Integer: set or get the current position of the large object. To set the position, simply assign the new position to the Position property as follows:

lo.Position = 20 // position the large object at offset 20

The beginning of a large object is position 0.



-----------------------
Details
-----------------------

As explained in the note that began this ReadMe, you must perform all large object operations inside of a transaction.

Most large object operations will be performed using an instance of the PostgreSQLLargeObject class, which you will obtain by calling the OpenLargeObject method of the PostgreSQLDatabase class. There is no reason to ever create your own PostgreSQLLargeObject instance using 'new'.

The PostgreSQLLargeObject class works a bit like a BinaryStream. As with BinaryStreams, PostgreSQLLargeObjects are always positioned at a certain location in the large object. Whenever you read or write to the large object, the position moves to just after the read or write. You can also set the position using the Position property. Advanced users can have even more control over the position by using the Seek method.

See the project that accompanies this ReadMe for an example of how to use PostgreSQL Plugin's large object API.